Installing the Library Using npm

The ChartIQ library archive includes a tarball (.tgz file) that allows you to install the charting library using npm.

Starting with version 9.5.1, ChartIQ also offers the library through a private npm registry.

Installing the library using the npm tarball

1. Obtain a copy of the library, and extract the archive (.zip file)

2. Copy the tarball (chartiq-x.x.x.tgz) to your project folder

   Note: The folder must contain a package.json file.

3. Install the library from the tarball using npm, for example:

   npm install ./chartiq-x.x.x.tgz
   

Your package.json file should now contain the following dependency:

"chartiq": "file:chartiq-x.x.x.tgz",

Note: When using the npm tarball, the ChartIQ dependency does not support version ranges with tilde (~) or caret (^) prefixes. Upon upgrading the charting library, including patch releases, you must replace the installed version with the new one. We recommend completely removing the old ChartIQ package before installing the new version. For example:

npm uninstall chartiq
npm install ./chartiq-x.x.x.tgz

Installing the library directly from npm (Version 9.5.1+)

ChartIQ now provides its library through a private npm registry, enabling you to download individual packages within the @chartiq namespace.

If you already have a copy of the library (version 9.5.1 or higher) in a zip file, you can find the packages listed in chartiq/webpack-example/package.json under the dependencies-use-for-npm section. Additionally, a list of available packages is provided below:

Key considerations:

• @chartiq/core is a dependency and must be installed for the other packages to function.
• If you are installing individual packages and want to use our existing sample templates, @chartiq/web-components is a required dependency.
• @chartiq/component-ui is a dependency but does not need to be explicitly installed unless the developer wants to access its functions directly.
• If you're using the dependencies list from chartiq/webpack-example/package.json, ensure you rename dependencies-use-for-npm to dependencies before installation.
• You may also want to adjust the versions of these packages to match your license version for stability, as they are currently set to "latest."

Available packages

Example:

npm install @chartiq/active-trader@latest

Logging into npm

To install the private ChartIQ npm packages, you must log in to npm via the command line. Please refer to the npm login documentation for detailed instructions.

Building a chart

Review this quick tutorial to get started with the ChartIQ Library installed via npm in a create-react-app project.

• Hello World Chart with React

Including all necessary files

The ChartIQ library includes a variety of file types: JavaScript files, CSS files, and image files of various kinds.

npm does not provide a way to load assets such as CSS and image files; you need to explicitly load them. You can use any solution you prefer, such as <link> tags, src attributes, or module bundlers such as webpack.

"Hot swapping" the keyfile

As of Version 9.0.0, the library archive also contains a keyfile that supplies your license key and entitlement information. It also allows you to extend or change the terms of your license without having to uninstall and reinstall the library or to replace all the locked files.

• When installing via the tarball, the keyfile can be found at node_modules/chartiq/key.js. Additionally, a copy will be available in the chartiq/ folder after unzipping your library archive.

• If you use the npm registry, please obtain the keyfile from your account manager. We generally provide a .zip file of the library that includes the keyfile, even if you choose the npm installation.

Simply replace the current keyfile with this new one — essentially "hot swapping" the keyfile.

Configuring keyfile "hot swapping" in a compiled app

If you are not bundling your code with a compiler, hot swapping will work right out of the box. However, if you are using a framework, bundling with webpack, or otherwise compiling your app, you need to do some initial configuration to enable hot swapping the keyfile without having to rebundle and redeploy your app.

Note: If you are actually upgrading the library, you will need to uninstall and reinstall, as explained above.

There are three main steps to enabling this feature:

1. Manually deploy the keyfile somewhere outside your compiled bundle.

   • You might modify your webpack build to include a plugin or some script to copy in the keyfile into your build. Or you might deploy the keyfile to a separate server.
   • If you are demoing a trial version of ChartIQ, you can just move the file into a location where your top-level html file can access it (such as the public folder in our sample React project).

2. In the <head> element of your page template (i.e. index.html), apply key.js as a module by adding a <script> tag with "module" as its type and the location of key.js as its source. For example:

   <head>
       <!-- other code -->
       <script type="module"
           src="<your deployed keyfile's location>">
       </script>
   </head>
   

   This will automatically add the function getLicenseKey to the global window object.

   Note: Your script tag needs to be in the head so that it runs before getLicenseKey is called.

3. In a chart container (e.g. Core.jsx in the folder react-components/src/Chart/Core.jsx in our sample React project):

   • Edit chartiq/key.js and delete or comment out the line that imports getLicenseKey.
   • Update the next line to call getLicenseKey from the global windows object.

   Note: If you are working with one of our sample framework projects, make sure you add this change to a component that loads before any others without this change. (The React project, for example, will error out if you update a component in src/containers without also updating one in react-components/src/Chart, which loads first.)

Example webpack configuration

The chartiq folder of your library contains sample webpack configuration files, including webpack.config.js, package.json, and a src folder that contains sample-template-webpack.js and index.html. Together, these files can be used to create a bundle from the ChartIQ library.

Important: The tarball version of the library does not include the webpack-example folder. Ensure you copy this folder over before proceeding.

See the Module Bundlers tutorial for more details.

Building with npm using packages from npmjs

When building with npm, you must specify the path to the key.js file. Below are some methods to do this:

1. Set an environment variable to specify the path to the key file.

   • The webpack.config.js file is configured to handle an environment variable named KEY_FILE_DIR.
   • You can also build using a command such as: KEY_FILE_DIR=./ npm run build.

2. Modify the path in your template to point to the location of your key.js file.

   • For example, change import getLicenseKey from "keyDir/key.js"; to import getLicenseKey from "path/to/key.js";.

3. Update the alias in webpack.config.js to explicitly point keyDir to key.js.

Already using npm?

Already using npm? If you had previously been using a custom solution to load the library as an npm package, you may need to revert your own solution to have everything working correctly. It may also be necessary to change any aliases that you have created. If you need any help migrating, please contact support@chartiq.com.

Next steps

• Essentials Overview
• Working with Module Bundlers